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A  Configuration  Management  Example 


James  E.Tomayko 
The  Wichita  State  University 


This  section  contains  examples  of  discrepancy  reports,  change  requests,  and  requests  for  enhancements  to 
products  to  show  their  differences  and  similarities. 

Real-Time  Hacking,  Inc.  (RTH),  a  defense  contractor,  decided  to  write  the  control  software  for  the  elevator  in  its 
new  engineering  building  to  provide  its  programmers  some  experience  with  Ada  before  its  use  was  mandated  in ' 
new  products.  A  team  leader  prepared  the  following  specification  and  partial  design  of  the  program:1 


Functional  Specification 

The  program  is  a  procedure  RUN_ELEVATOR  that  controls  an  elevator  serving  8  floors  of  a  building,  num¬ 
bered  from  1  to  8  (no  basement). 

At  each  floor  in  the  building  are  two  elevator  call  buttons-UP  and  DOWN  (except  for  the  first  floor  which  does 
not  have  a  DOWN  button  and  the  top  floor  which  does  not  have  an  UP  button).  Inside  the  elevator  there  are  8 
FLOOR  buttons,  one  for  each  of  the  8  floors  and  an  OPEN  button.  FLOOR  button  marked  I  is  depressed  by  a 
passenger  to  get  off  at  floor  I  and  the  OPEN  button  is  depressed  to  prolong  the  period  the  elevator  door  is  open. 

Elevator  Specification:  The  elevator  car  behaves  as  follows: 

1.  It  services  the  8  floors  carrying,  passengers  up  and  down:  Its  home  floor  is  the  first  floor  (the  building 
lobby).  Whenever  there  are  no  requests  for  use,  it  stations  itself  at  the  home  floor. 

2.  When  going  up,  the  elevator  services  all  requests  for  stops  on  floors  above  its  current  position;  similarly 
when  it  is  going  down.  The  elevator  tries  to  minimize  die  number  of  changes  in  direction:  (No  person 
waits  forever.) 

3.  The  elevator  opens  its  door  for  5  seconds:  Every  time  the  OPEN  button  is  pressed,  the  door  is  kept  open 
for  one  extra  second.  However,  pressing  the  OPEN  button  when  the  door  is  closed  has  no  effect. 


Physical  Details  of  the  Elevator:  Depressing  an  elevator  button  causes  a  hardware  interrupt  (with  a  possible 
parameter)  on  the  computer  associated  with  the  elevator  These  interrupts  are  queued  automatically:  Hardware 
addresses  corresponding  to  these  interrupts  are 


Button 

Address 

Function 

DOWN(I) 

8#1000# 

Request  to  go  down  from  floor  1 

UP(I) 

8#1010# 

Request  to  go  up  from  floor  1 

FLOOR(I) 

8#1020# 

Stop  at  floor  1 

OPEN 

8#1030# 

Delay  closing  door  by  one  second 

A  package  ELEVATOR  with  the  following  specification  is  available. 


'The  specification  and  partial  implementation  of  this  example  are  adapted  by  permission  from  N train  Gehani,  Ada:  An  Advanced 
Introduction  (Prentice-Hall,  1983,  pp.  181-200).  Ada  is  a  trademark  of  the  U.S.  Department  of  Defense. 
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package  ELEVATOR  is 

procedure  MOVE_UP_ONE_FLOOR; 
procedure  MOVE_DOWN_ONE_FLOOR; 
procedure  CLOSE_DOOR; 
procedure  OPEN_DOOR; 
end  ELEVATOR; 

Elevator  Movement  Timing  Characteristics:  The  elevator  movement  consists  of  three  phases-the  car  first 
accelerates  to  steady  speed,  then  travels  at  steady  speed  and,  finally,  decelerates  to  a  stop.  The  elevator  takes 
1.80  seconds  to  go  from  a  stationary  position  at  floor  I  to  a  stationary  position  at  floor  1+1  (the  characteristics  are 
the  same  whether  the  elevator  is  going  up  or  down)-0.40  seconds  to  accelerate  to  steady  speed  while  covering 
the  distance  A^,  1.00  seconds  traveling  at  steady  speed  to  cover  the  distance  BjCj,  and  0.40  seconds 
decelerating  to  a  stop  while  covering  the  distance  CjDj.  AjBj  is  equal  to  CjDj,  Aj  coincides  with  Dj-1  and  Dj 
coincides  with  Aj+1. 

If  there  is  no  need  for  the  elevator  to  stop  at  the  next  floor  then  it  must  be  given  another  move  command  before 
it  starts  decelerating,  i.e.,  at  or  before  position  Cj.  There  are  two  cases: 

1.  Suppose  the  elevator  is  in  a  stationary  position  at  the  time  the  first  move  command  is  given:  Then  the 
elevator  should  be  given  the  next  move  command  at  most  1.40  seconds  after  the  previous  move  com¬ 
mand 

2.  Suppose  the  elevator  starts  from  floor  1-1  or  earlier.  It  does  not  stop  at  floor  1  and  is  not  to  stop  at  floor 
1+1  either.  It  was  last  instructed  to  keep  moving  at  position  Cj-1.  It  must  now  be  instructed  to  keep 
moving  at  Cj.  Traveling  at  steady  speed  the  elevator  covers  the  distance  AjBj  or  CjDj  in  half  the  time  it 
takes  when  accelerating  or  decelerating.  Consequently,  it  covers  the  distance  Cl-lCj  in  1.40  seconds. 
The  next  move  command,  as  in  the  first  case,  must  be  given  at  most  1.40  seconds  after  the  previous 
move  command. 


Design 

Requests  for  elevator  service,  to  go  up  or  down,  or  to  get  off,  are  accepted  by  a  task  REQUEST_DB  (requests 
data  base),  which  also  keeps  track  of  these  requests.  Task  ELEVATOR_CONTROL  controls  the  elevator  using 
commands  provided  in  the  package  ELEVATOR:  It  also  accepts  requests  from  passengers,  made  by  depressing 
the  OPEN  button,  to  keep  the  elevator  door  open  longer  than  the  normal  period.  Task 
ELEVATOR_CONTROL  interacts  with  the  task  REQUEST_DB  to 

1.  determine  the  next  elevator  destination  based  on  pending  requests  for  elevator  serv.ee,  and 

2.  supply  information  specifying  the  floors  that  have  been  serviced. 

The  interaction  between  tasks  ELEVATOR_CONTROL,  REQUEST_DB,  package  ELEVATOR  and  the 
elevator  itself  is  illustrated  in  Figure  1. 

At  any  time,  die  elevator  will  be  in  one  of  three  states-UP,  DOWN  or  NEUTRAL:  States  UP  and  DOWN 
indicate  that  the  elevator  is  going  in  the  direction  implied  by  its  state  in  response  to  passenger  requests.  The 
NEUTRAL  state  indicates  that  the  elevator  is  not  responding  to  a  request  but  that  it  might  be  headed  toward  its 
home  floor  if  it  is  not  already  there. 
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Some  constant  and  type  declarations  used  in  the  implementation  are: 

HOME:  constants  1; 

N:  constants  8;  --number  of  floors 

subtype  STORIES  is  INTEGER  range  1..N; 
type  STATE  is  (UP,  DOWN,  NEUTRAL): 

NORMAL_OPEN_TlME:  constant  DURATION:*  5.0; 
EXTRA_OPEN_TIME:  constant  DURATION:*  1.0; 
NEXT_MOVE_TIME:  constant  DURATION:*  1.39 
--the  next  move  command  must  be  given  at  most 
-1:40  seconds  after  the  previous  move  command; 
“Selection  of  1 :39  is  arbitrary  except  for  the 
-above  constraint 


The  specification  of  task  ELEVATOR_CONTROL  is 

task  ELEVATOR_CONTROL  is 

entry  OPEN;  -keep  the  door  open  one  second  longer 
-associate  hardware  interrupt  location  with  entry  OPEN 
for  OPEN  use  at  8#1 030#; 
end  ELEVATOR_CONTROL; 


The  specification  of  task  REQUEST_DB  is 
•  task  REQUEST_DB  is 

entry  DEST(CUR_STATE:  In  STATE;  CUR_FLOOR:  In  STORIES; 

NEW_STATE:  out  STATE; 

NEW_FLOOR:  out  STORIES); 

-computes  the  new  destination  and  direction 
-based  on  the  current  location,  current 
-direction  and  pending  requests 
entry  REQUESTS  (B:  out  BOOLEAN);, 

-TRUE  returned  in  B  if  there  is  any  pending  request 
-for  elevator  service  and  FALSE  otherwise 
entry  CLEAR_GO(DIR:  in  STATE;  I:  in  STORIES); 

-picked  up  passenger(s)  going  up  or  down  from  floor  I 
entry  CLEAR_OFF(l:  In  STORIES); 

-passenger(s)  let  off  at  floor  I 

-the  following  entries  correspond  to  passenger 
-requests  for  elevator  service 
entry  DOWN  (I:  In  STORIES); 
entry  UP(I:  In  STORIES); 
entry  FLOOR(l:  In  STORIES):, 

-associate  hardware  interrupt  locations  with  entries 
for  DOWN  use  at  8#1000#; 
for  UP  use  at  8#1 010#; 
for  FLOOR  use  at  8#1 020#; 
end  REQUEST_DB; 
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RTH’s  configuration  manager  placed  the  Functional  Specification  and  Design  documents  under  configuration 
control  when  the  program  entered  its  implementation  phase,  even  though  it  was  an  informal  development  project 
and  not  intended  as  a  product  She  also  wanted  to  get  some  Ada  experience.  This  turned  out  to  be  fortunate,  as  a 
fluny  of  discrepancy  reports  began  to  surface  during  integration  testing.  A  configuration  control  board  consist¬ 
ing  of  the  author  of  the  functional  specification,  a  representative  from  the  test  and  evaluation  team,  the  division 
manager  whose  engineers  were  doing  the  Ada  excercise,  and  the  configuration  manager  hastily  convened.  The 
division  chief  had  the  responsibility  for  the  final  decision  on  discrepancy  reports  and  change  requests. 


A  Discrepancy  Report 

One  of  the  discrepancy  reports  die  board  considered  was  turned  ir  ,y  a  test  engineer  (See  Figure  2). 

The  origins  of  this  problem  lie  in  a  typographical  error  that  mushroomed  across  the  system.  The  existing 
mechanical  elevator  control  system  accelerated  and  decelerated  in  1.4  seconds.  The  author  of  die  Functional 
Requirements  mistakenly  wrote  0.4  seconds.  The  engineers  designing  the  changes  to  the  hardware  needed  to 
transition  to  the  digital  system,  aware  of  the  Functional  Specification  of  the  software,  interpreted  the  value  0.4  as 
a  virtual  change  request  to  their  equipment.  Since  the  work  was  being  done  by  RTH’s  in-house  staff  and  not  by 
the  elevator  manufacturer,  they  did  not  realize  that  0.4  seconds  was  a  little  fast,  they  thought  it  was  a  benefit  to 
be  gained  by  using  software  control!  The  engineer  writing  the  discrepancy  report,  thinking  that  the  software  was 
the  only  new  element  in  the  system,  flagged  the  software,  but  put  a  few  question  marks  next  to  the  hardware 
classification  because  he  really  did  not  know. 

The  configuration  control  board  quickly  realized  that  the  software  was  not  controlling  acceleration  and  decelera¬ 
tion  rates,  but  merely  had  to  be  aware  of  them  for  the  NEXT_MOVE_TIME  parameter  to  be  correct.  Therefore 
an  easy  fix  to  the  documentation  and  code  could  be  made,  but  it  took  nearly  a  week  to  run  down  who  hau 
changed  the  hardware.  If  the  system  had  been  organized  as  a  product  development  effort  from  the  start,  a  design 
review  on  the  hardware  side  should  have  detected  the  error  in  changing  the  elevator’s  existing  acceleration  and 
deceleration  rates. 

Note  that  the  discrepancy  report  form  used  here  has  provision  for  tracking  the  disposition  all  the  way  through  to 
the  verification  of  the  actual  changes,  including  forcing  the  originator  to  sign  off  that  the  analysis  of  the  problem 
is  understood  by  him. 


A  Change  Request 

During  the  testing  period  of  the  new  system,  a  handicapped  secretary  sitting  in  a  wheelchair  found  herself  in  the 
back  of  the  elevator  with  several  people  standing  in  front  of  her.  When  she  reached  her  floor,  the  standees  filed 
out  somewhat  slowly.  She  got  near  the  door  as  it  started  to  close,  hit  the  ’Door  Open’  button  once,  and  then 
nearly  got  trapped  when  she  could  not  clear  the  doors  during  the  one  second  delay.  The  result  of  this  incident 
was  Figure  3,  a  change  request. 

The  configuration  control  board  evaluation  of  this  change  was  fairly  straightforward,  in  that  it  was  obviously 
needed.  However,  the  change  cost  considerable  money  as  the  implementation  group  first  tried  stacking  ’Door 
Open’  requests  so  that  every  time  someone  pushed  the  button  a  one  second  delay  was  stored.  That  way  five 
pushes  equalled  five  seconds,  and  the  users  could  actually  control  the  length  of  the  delay.  One  day  the 
president’s  four-year-old  hit  the  button  36  times  while  the  doors  were  open,  resulting  in  another  change  request 
by  the  person  who  had  just  boarded  the  elevator  wanting  to  go  down.  The  original  change  request  form  used  had 
no  provision  for  sign-offs  by  the  verfication  or  quality  assurance  teams,  so  the  implementor’s  interpretation  of 
the  phrase  ’to  3  seconds’  was  not  challenged.  The  final  fix  was  to  change  the  value  of  the  constant 
EXTRA_OPEN_TIME  to  3.0  seconds. 


Requests  for  Enhancements 

After  the  RUN_ELEVATOR  program  finally  was  in  operational  use,  the  president  of  Death  Rays,  Inc.  visited 
RTH.  Tne  president  of  RTH,  made  aware  of  the  Ada  elevator  controller  due  to  his  son’s  exploit,  bragged  to 
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Death  Rays’  president  about  the  program.  It  turned  out  that  Death  Rays  was  completing  a  new  corporate  head¬ 
quarters,  and  became  interested  in  purchasing  the  program  to  prove  that  they  had  some  Ada  in  house.  In  order  to 
help  keep  Death  Rays’  business,  the  president  of  RTH  ordered  a  new  version  of  the  program. 

The  configuration  manager  was  infuriated.  What  had  started  as  an  ad  hoc  programming  project  had  evolved  into 
an  ongoing  product  development  effort.  The  program  was  informally  described,  had  no  user  or  installation 
documentation,  and  no  consistent  control  had  been  applied  to  its  evolution.  The  cost  of  adding  discipline  at  this 
point  was  expensive,  yet  no  formal  control  board  existed  to  draw  attention  to  this  fact  Production  of  the  new 
version  of  the  program  began.  The  implementors  thought  it  would  be  an  easy  deal:  find  out  how  many  floors, 
check  out  the  constants  (this  time  they  called  the  elevator  manufacturer  and  subcontracted  any  hardware  changes 
to  them),  and  everything  would  be  an  easy  fix. 

The  program  was  changed,  delivered,  and  installed.  One  hour  later  the  customer  version  of  a  discrepancy  report 
(an  Information  and  Assistance  Request)  arrived  by  messenger  (see  Figure  4).  The  members  of  the  ad  hoc 
configuration  control  board  met  hastily  over  lunch:  The  problem  and  its  resolution  can  be  deduced  from  the 
form. 

Several  months  later,  after  everyone  had  nearly  forgotten  about  RUN_ELEVATOR,  a  friend  of  the  president  of 
Death  Rays  called  the  president  of  RTH.  He  was  building  a  huge  new  corporate  headquarters.  It  had  three 
elevators.  The  president  of  RTH,  still  wanting  to  keep  Death  Rays’  business,  picked  up  the  phone  to  call  the 
software  shop . 
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IMPROVEMENT 


SOFTWARE  PROBLEM  REPORT 


MFNO:__ 

MEIMffA-CCn 


OmOMATQMIKAMC 


*T*T!*!.  Run  Elevator 


EHXMOOUlf 


MLATtO 
systems . 


CLASNEICATtON: 
nOTWMNC  „„„ 

OMAMOWAMt  ??? 
OCOMMSNTWOL 

OOOCUMSWTATK3M 
O  MTOMMTION  OMCV 


MtATiO 

_ TUTCAM  ■ 

_  The  elevator  we  are  testing  using  the 

Version  lTl  ofthe  sottware  accelerates  and  decelerates 
excessively  last.  People  have  trouble  staying  on  their  reel 


MCMMOSY: 
AMA4.VM  TO  •( 


SKMATUAC 


OATt  8/7/86 


ANALYSIS:  ISMCSAAEO  SY  MVONMU  nn«MM  OUMN ONOANUATIONI  NICCtVtOOATC  Q./J  >n£ 

ts#*  Requirements  error - the  values  stated  iri 

_  -  Functional  Specification,  section  T73  £or  acceleration/ 


CLASMSICATION: 

OOOOtNG 

OOSSNIM 

OCOMMSMT/POl 

0 OOCUMSNTATKX 

OtMVMtOMMCNT 

O  NO  t/W  CNAMGC  NCQO 

ONSPOATSDON . . 

PACVtOUSlY 

OOTHWCSWIC 

AAMCTEO 

MM  NO - 1 


kTUASS:  .AhC.  ,  AWALTST. 


Functional  Specification,  section  1.3  for  acceleration/ 
deceleration  are  "OF  seconds  ior  each.  Actual  values  are 


seconds  tor  each. 


.  ONNUNATOA 


XlnllL 


OOANCCnON:  WA1EP  OCSCRWTION  OS  WON*  ANO  LIST  OP  MOOULtS  CHANGED! 
rrrmi womr  Since  acceleration  and  deceleration  are  functions  of  the  hardware 
the  only  chance  needed  is  in  the  declaration  of  NEXT_M0VE_T1ME  in  the  Design 


document,  as  follows 


constant 


comment  and  tunctiona 


OQCUMfKTATKM  MONK:  MArtf  OCKNMTMN  Of  DOCUM< 

Section  1.3  changed,  Design  changed. 


INTATION  WOAKI 


Functional  Specification 


SAW  OMO. . 

saw  o  no., 
saw  o  no. . 

SAW  O  NO. 


PACE  MO. 
PASS  NO. 
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Support  Materials 


Examples  of  Software  Change  Forms 


James  E.  Tomayko 
The  Wichita  State  University 


The  following  five  pages  arc  examples  of  forms  used  in  industry  for  customers  and  developers  to  report  software 
problems  and  request  changes.  Included  are: 

1 .  Discrepancy  Report  Form 

2.  Request  for  Change  Form  (1) 

3.  Request  for  Change  Form  (2) 

4.  Software  Problem  Report  Form  (Boeing) 

5.  Information  and  Assistance  Request  Form  (used  by  customers  only) 

Pages  11  through  15  are  unnumbered. 
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1.  Introduction 

This  plan  is  based  on  ANSI/IEEE  Standard  828-1983,  section  3.  Also  used  were  "Outline  for  a  Configuration 
Management  Plan  for  Computer  Programs"  and  "Software  Requirements,  Baselining,  and  Control",  both  from  Data  and 
Configuration  Management  Workshops  of  the  Electronics  Industries  Association. 

There  are  two  teams  for  this  project,  each  with  an  identical  Configuration  Management  organization.  Both  teams  will 
use  this  plan.  In  some  areas,  the  teams  will  differ;  for  example,  they  will  use  different  revision  control  procedures.  These 
differences  will  be  noted  below. 

1.1  Purpose 

The  purpose  of  this  plan  is  to  describe  and  define  the  policies  and  proceedings  to  be  used  in  the  application  of 
configuration  management  to  the  development  of  the  Mars  Research  Station  Operational  Simulator  (Mars  OpSim). 

1.2  Scope 

This  plan  provides  for  the  application  of  configuration  identification,  control,  and  status  accounting  during  the 
development  of  Mars  OpSim.  Included  is  the  assignment  of  item  numbers  tc  the  Computer  Program  Configuration  Items 
(CPCI),  revision  control  during  development,  procedures  to  be  followed  to  ensure  interface  control,  and  identification  of 
status  accounting  techniques  and  procedures. 

1.3  Definitions  and  acronyms 

The  terms  relating  to  configuration  management  used  in  this  document  are  defined  by  EIA  Configuration  Management 
Bulletin  No.  4  A,  Configuration  Management  for  Digital  Computer  Programs. 
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2.  Management 

2.1  Organization 

The  Configuration  Manager  will  report  directly  to  the  contract  monitor.  Responsibility  and  authority  has  been  delegated 
to  the  Configuration  Manager  by  the  contract  monitor  to  act  for  him  in  all  matters  relating  to  the  implementation  of 
Configuration  Management  in  accordance  with  this  plan. 

The  Configuration  Control  Board  (CCB)  is  appointed  by  the  Configuration  Manager  for  the  purpose  of  evaluating  all 
proposed  changes  to  ieleased  specifications,  computer  programs,  manuals,  design  documents,  listings,  and  other  items 
identified  for  formal  change  control. 

2.2  CM  responsibilities 

The  Configuration  Manager  is  responsible  for 

•  Writing  the  Configuration  Management  Plan. 

•  Appointing  the  Configuration  Control  Board  and  presiding  over  its  meetings. 

•  Creating  the  necessary  forms  for  CM  procedures. 

•  Maintaining  easily-accessible  central  repositories  for  the  current  versions  of  the  software  configuration  items  in 
machine-readable  form. 

•  Maintaining  records  of  CM  activity. 

•  Preparing  releases  of  configuration  items  and  providing  for  their  distribution. 

•  Receiving  change  requests  and  discrepancy  repeats  and  presenting  them  to  the  CCB. 

•  Ensuring  that  approved  changes  are  made  and  recorded. 

•  Conducting  audits  of  the  CM  process. 

2.3  SCMP  implementation 

2.3.1  Configuration  Control  Board 

The  Configuration  Control  Board  will  consist  of  five  members:  the  Configuration  Manager  (chairman),  the  Quality 
Assurance  Manager,  the  Project  Administrator,  and  one  member  each  of  the  Design  and  Coding  teams.  One  member  will 
be  selected  by  the  board  to  be  secretary,  and  will  keep  minutes  of  each  meeting. 

2.3.2  Central  repositories 

There  will  be  central  repositories  maintained  by  the  Configuration  Managers  for  the  current  releases  of  all  software 
configuration  items. 

2.3.2.1  Documentation  repositories 

Two  directories  will  be  maintained  on  TOPS  machines  for  copies  of  the  current  releases  of  documentation  items. 
Current  releases  of  all  Ada  documentation  will  be  kept  in  the  <ws  0N>  directory  on  TOPS-D  (td .  cc .  emu .  edu).  Current 
releases  of  all  Pascal  documentation  will  be  kept  in  the  <  JL13>  directory  on  TOPS-C  (tc .  cc .  emu .  edu).  Copies  of 
general  project  documentation  will  be  kept  in  both  directories.  Filenames  will  use  the  naming  convenuons  of  Sevtxun . 
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2322  Code  repositories 

The  Unix  RCS  system  will  be  used  to  manage  the  Ada  team’s  code.  A  central  RCS  directory  on  the  project  VAX  will  be 
maintained  for  source  code  version  control.  In  addition,  a  directory  containing  copies  of  the  current  release  of  source  code, 
object  code,  and  libraries  will  be  maintained. 

The  current  releases  of  Pascal  source  code,  object  code,  and  libraries  will  be  kept  in  the  <  JL13>  directory  on  TOPS-C. 
Backup  floppies  will  be  kept  by  the  Configuration  Manager. 


23 3  Releases 

A  release  of  a  configuration  item  will  result  in,  the  updating  of  that  item  in  the  appropriate  repository,  the  notification  of 
all  project  members,  and  possibly  the  distribution  of  human-readable  copies. 

Releases  will  be  made  periodically;  the  period  between  releases  will  depend  on  the  frequency  and  urgency  of  changes 
made.  A  release  will  be  made  immediately  prior  to  each  review. 


2.3.4  Change  requests  and  discrepancy  reports 

Change  requests  and  discrepancy  reports  will  be  given  to  the  Configuration  Manager  for  introduction  at  the 
Configuration  Control  Board  meetings.  A  central  mailbox  will  be  established  for  this  purpose. 

2.4  Applicable  policies,  directives,  and  procedures 

2.4.1  Release  policy 

Software  will  be  released  and  placed  under  formal  change  control  at  the  formal  request  of  the  group  responsible  for 
developing  the  software;  for  example,  a  Coding  team  member  might  send  electronic  mail  to  the  CM  at  the  completion  of  a 
module’s  unit  testing.  After  software  has  been  released,  it  will  not  be  changed  unless  as  a  result  of  an  approved  change 
request.  Periodically,  as  determined  by  the  CCB,  a  new  release  containing  the  changes  will  be  made,  and  copies  will  be 
placed  in  the  release  directory. 


2.4.2  RCS  usage  policy 

RCS  will  be  used  to  maintain  all  released  Ada  source  code.  Those  groups  working  on  Ada  software  are  strongly 
encouraged  to  use  RCS  internally  as  well. 

The  RCS  Header  string  will  be  used  in  all  Ada  source  files  in  a  manner  that  ensures  the  inclusion  of  the  header  string  in 
the  object  code.  The  RCS  Log  feature  will  be  used  in  all  Ada  source  files  within  comments. 


2.4.3  Pascal  coding  policy 

It  will  be  the  responsibility  of  those  working  on  Pascal  software  to  use  the  most  recent  available  versions  of  released 
software,  and  to  keep  their  working  versions  up  to  date. 


2.4.4  Standard  routine  headers 

Standard  templates  to  be  provided  by  the  Configuration  Managers  will  be  used  for  the  opening  comment  of  all  modules 
and  routines  to  ensure  consistency  in  the  information  provided.  The  actual  templates  will  be  designed  in  oooperauon  with 
the  Design  and  Coding  teams  and  made  available  in  the  release  directories,  they  may  not  necessarily  look  like  the  samples 
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below. 

2.4.4.1  Sample  Ada  file  header 


—  Mars  OpSim 

—  Module :  Queue 

--  File :  queue-insdel . a 

—  Routines: 

Queue. Insert  Insert  an  element  into  a  queue 

—  Queue. Delete  '  Delete  an  element  from  a  queue 

—  $Header:  queue-insdel. a, v  1.1  86/10/23  04:23:33  wrs  $ 

~  $Log:  queue-insdel. a, v  $ 

—  Revision  1.1  86/10/23  04:23:33  wrs 

—  SCR  25  ;  Fixed  MemFull  exception  bug  in  Queue. Insert 

—  Revision  1.0  86/10/11  01:29:22  wrs 

—  Initial  release 
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2.4.4 2  Sample  Ada  routine  header 


—  Routine: 

—  Author: 

—  Function: 


Queue . Insert 
Joe  Programmer 

Insert  an  element  into  a  queue. 


—  Inputs :  q 

elt 

—  Outputs :  q 

—  Exceptions :  MeaFull 

—  Globals  used:  none 


The  queue 

The  element  to  be  inserted 
(modified) 


—  Specification: 

—  This  routine  inserts  elt  at  the  tail  of  q.  If  there  is 

—  insufficient  memory,  the  MamFull  exception  is  raised. 


—  Implementation : 

—  Memory  is  allocated  for  elt.  If  there  is  insufficient .. .etc. 


—  Side  Effects: 

—  none 


—  Modification  history: 

—1.1  86/10/23  *rs 

SCR  25  ;  Fixed  MemFull  exception  bug. 

—  Missed  post-allocation  memory  compaction  problems. 

—1.0  86/10/11  wrs 

Initial  release 


2.4.4 .3  Sample  Pascal  file  header 
(  Mars  OpSim 

Module :  Queue 

File :  queue-insdel . pas 

Routines : 

Queue_Insert  Insert  an  element  into  a  queue 
Queue_Delete  Delete  an  element  from  a  queue 

Last  Edit:  10/23/86  by  jll 

Revision  History: 

1.1  10/23/86  jll 

SCR  25  ;  Fixed  MemFull  error  bug  in  Queue  Insert 
1.0  10/11/86  jll 

Initial  release 

) 


6 


2.4 .4.4  Sample  Pascal  routine  header 
{ 

Routine :  Queue_Insert 

Author :  Joe  Programmer 

Function:  Insert  an  element  into  a  queue. 

Inputs:  q  The  queue 

elt  The  element  to  be  inserted 
Outputs :  q  (modified) 

Globals  used:  none 

Specification : 

This  routine  inserts  elt  at  the  tail  of  q.  If  there  is 
insufficient  memory,  the  MemFull  handler  is  called. 

Implementation : 

Memory  is  allocated  for  elt.  If  there  is  insuf f icieut . . . etc . 

Side  Effects: 
none 

Modification  history: 

1.1  86/10/23  jll 

SCR  25  ;  Fixed  MemFull  error  bug. 

Missed  post-allocation  memory  conqpaction  problems. 

1.0  86/10/11  jll 

Initial  release 

) 


7 


3.  SCM  Activities 

3.1  Configuration  identification 

3.1.1  Naming  conventions 

3.1.1.1  Documentation 

Documentation  configuration  items  will  be  identified  by  a  two-part  code  D-R  where  D  is  a  code  for  the  document  and  R 
is  the  release  number  of  that  document.  Releases  will  be  numbered  consecutively  from  one.  Unreleased  versions  of 
documents  will  have  an  additional  number  identifying  the  last  change  applied.  This  number  will  start  at  one  and  be 
incremented  by  one  at  each  change.  For  example,  the  second  release  of  the  Software  Requirements  Document  would  be 
called  SRD-2;  after  five  changes  had  been  applied,  it  would  be  called  SRD-2-5. 

Filenames  for  the  machine-readable  versions  of  documents  will  follow  the  same  conventions;  for  example,  the  Scribe 
source  for  SRD-2-5  would  be  called  SRD-2-5  .MSS.  On  Unix  systems,  lower-case  letters  will  be  used:  srd-2-5  .mss. 

3.1.1.2  Code 

Source  code  modules  will  be  identified  by  a  module  name  not  longer  than  ten  characters.  Releases  of  source  code 
modules  will  be  numbered  consecutively  from  one,  and  will  be  called  "ModuleName  Release  n",  where  n  is  the  release 
number.  Unreleased  versions  of  source  code  modules  will  have  an  additional  number  identifying  the  last  change  applied. 
This  number  will  start  at  one  and  be  incremented  by  one  at  each  change.  For  example,  the  second  release  of  the  Queue 
module  would  be  called  "Queue  Release  2";  after  five  changes  had  been  applied,  it  would  be  called  "Queue  Release  2.5". 
RCS  version  numbers  of  source  files  will  be  made  to  correspond  to  module  release  numbers. 


3.1.2  Configuration  items 

The  configuration  items  for  this  project  (and  their  codes,  where  applicable)  will  be 

•  Software  Requirements  Document  (SRD) 

•  Software  Specifications  Document  (SSD) 

•  Preliminary  Design  Document  (PDD) 

•  Software  Design  Document  (SDD) 

•  Software  Test  Plan  (STP) 

•  User  Document  (UD) 

•  Individual  software  modules  (as  defined  by  the  SSD) 

•  Individual  software  source  files  (as  defined  by  the  SDD) 

•  Individual  object  code  files  (as  defined  by  the  SDD) 

3.1.3  Baselines 

Six  baselines  will  be  defined:  Requirements,  functional,  allocated,  design,  product,  and  operational.  Releases  will  update 
these  baselines. 
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3.13.1  Requirements  baseline 

The  requirements  baseline  is  established  at  the  Requirements  Review.  It  consists  of  the  Software  Requirements 
Document. 

Once  the  requirements  baseline  is  complete,  the  general  specifications  are  created,  establishing  the  functional  baseline. 

3.132  Functional  baseline 

The  functional  baseline  is  established  at  the  Specifications  Review.  It  consists  of  the  Software  Requirements  Document 
and  the  Software  Specifications  Document 

Once  the  functional  baseline  is  complete,  the  preliminary  design  specifications  are  created,  establishing  the  allocated 
baseline. 

3.133  Allocated  baseline 

The  allocated  baseline  is  established  at  the  Preliminary  Design  Review.  It  consists  of  the  Preliminary  Design  Document, 
the  Software  Test  Plan,  the  User  Document,  and  the  components  of  the  functional  baseline. 

This  baseline  allows  the  detailed  design  process  to  begin.  Once  all  software  components  have  been  designed,  the  design 
baseline  is  established. 

3.13.4  Design  baseline 

The  design  baseline  is  established  at  the  Critical  Design  Review.  It  consists  of  the  Software  Design  Document  and  the 
components  of  the  allocated  baseline. 

This  baseline  starts  the  actual  process  of  coding  and  debugging.  As  each  routine  completes  its  unit-level  test,  it  will  be 
released,  establishing  the  product  baseline. 

3.133  Product  baseline 

The  product  baseline  is  established  by  the  integration  of  all  software  components  and  the  release  of  the  software  to  the 
Test  and  Evaluation  group.  It  consists  of  all  of  the  configuration  items. 

Once  all  design  descriptions  have  been  validated  against  the  requirements  and  all  software  components  have  passed 
acceptance  tests,  the  operational  baseline  is  established. 

3.13.6  Operational  baseline 

The  operational  baseline  is  established  when  the  product  has  passed  acceptance  testing  and  has  been  released  to  the 
customer.  It  consists  of  all  of  the  configuration  items. 

3.2  Configuration  control 

Configuration  control  is  the  systematic  evaluation,  coordination,  and  approval  or  disapproval  of  proposed  changes  to  a 
baseline.  Formal  control  of  the  configuration  of  an  item  begins  with  the  definition  and  release  of  a  baseline  for  that  item. 


3.2.1  Change  classification 

Class  I  A  Class  I  change  is  defined  as  any  change  which  affects  a  customer  approved  reqiarements,  functional, 

allocated,  product,  or  operational  baseline. 

A  Class  II  change  is  deTned  as  ar.y  change  which  is  not  Class  I  or  any  change  wmch  corrects  errors  in 


Class  n 
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the  documentation  of  a  customer-approved  baseline. 

All  Class  I  changes  must  be  approved  by  the  contract  monitor.  Class  II  changes  can  be  approved  by  the  Configuration  , 
Control  Board.  The  contract  monitor  may  override  the  CCB’s  classification  of  any  change. 


3.2 2  Configuration  Control  Board 

The  CCB  will  review  all  change  requests  and  discrepancy  reports.  The  total  impact  of  each  request  will  be  evaluated  by 
the  board,  taking  into  consideration  appropriateness,  cost,  technical  feasability,  scheduling  constraints,  effects  on  other 
items,  and  effects  on  testing. 

Class  II  changes  will  be  approved  or  disapproved  by  the  CCB.  Class  I  changes  for  which  the  CCB  recommends  approval 
will  be  forwarded  to  the  contract  monitor  for  final  approval  or  disapproval.  The  CCB  will  designate  an  implementor  for 
each  fully  approved  change. 

The  CCB  will  be  convened  on  a  weekly  basis  or  as  deemed  necessary  by  the  Configuration  Manager.  Copies  of  change 
requests  and  deficiency  reports  will  be  made  available  to  CCB  members  prior  to  meetings  for  examination  and  evaluation. 
Minutes  of  each  meeting  will  be  distributed  to  all  project  members. 

A  joint  meeting  of  the  Ada  and  Pascal  CCB’s  may  occasionally  be  called  to  discuss  matters  of  mutual  concern. 


3.2 3  Change  Control  Documentation 

Two  documents  will  be  used  to  process  and  control  changes:  the  Software  Change  Request  and  the  Software 
Discrepancy  Report.  The  Change  Request  will  be  used  for  requesting  a  change  to  a  released  configuration  item  that  is  an 
improvement  rather  than  a  repair.  The  Discrepancy  Report  will  be  used  for  requesting  a  change  to  a  released  configuration 
item  necessary  because  of  a  failure  of  the  item  to  meet  requirements. 


3.2.4  Change  processing 

A  change  request  will  be  processed  in  the  following  manner: 

1.  A  change  request  is  prepared. 

2.  It  is  transmitted  to  the  Configuration  Manager,  who  numbers  the  change  for  tracking  purposes  and  notifies  the 
Configuration  Control  Board. 

3.  The  Board  classifies  the  change  and  may  then 

•  approve  a  Class  n  change,  or  approve  the  submission  of  a  Class  I  change  to  the  contract  monitor 

•  disapprove  the  change,  in  which  case  the  change  dies 

•  modify  the  proposed  change,  in  which  case  the  modifications  are  made  and  the  change  is  reevaluated 

4.  If  a  change  is  approved,  it  is  implemented  by  someone  designated  by  the  Board. 


3.2.5  Discrepancy  Report  processing 
A  discrepancy  report  will  be  processed  in  the  following  manner 

1.  A  discrepancy  report  is  prepared. 

2.  It  is  transmitted  to  the  Configuration  Manager,  who  numbers  it  for  tracking  purposes  and  notifies  the 
Configuration  Control  Board. 

3  The  Board  may  immediately  reject  the  report,  in  which  case  it  dies,  or  assign  someone  to  analyze  the  report 
and  prepare  a  correction. 

4.  If  the  report  is  not  rejected,  the  board  may  approve,  disapprove,  or  modify  the  proposed  correcuon. 
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5.  If  the  correction  is  approved,  it  is  implemented  by  someone  designated  by  the  Board. 


3.3  Configuration  status  accounting 

The  following  status  accounting  logs  and  reports  will  be  maintained: 

Configuration  Item  Index 

The  Configuration  Item  Index  will  list  each  configuration  item  along  with  its  creation  date,  current 
released  version,  and  the  versions  of  its  component  items. 

RCS  change  logs  RCS  change  logs  will  be  maintained  for  each  Ada  source  file.  They  will  show  the  history  of  the 
changes  made  to  the  source  files,  as  well  as  their  release  histories. 

Pascal  change  logs  Each  pascal  source  file  will  contain  a  change  log  showing  the  history  of  the  changes  made  to  it,  as  well 
as  its  release  history. 

Discrepancy  reports 

All  Software  Discrepancy  Reports  will  be  retained. 

Change  requests  All  Software  Change  Requests  will  be  retained. 


3.4  Audits  and  reviews 

The  Configuration  Manager  will  periodically  audit  the  system  to  ensure  that  policies  and  procedures  arc  being  fallowed. 
Audits  will  be  conducted  as  follows: 


Requirements 

Functional 

Allocated 


Design 


Product 

Operational 


At  the  Requirements  Review,  the  CM  will  release  the  Software  Requirements  Document  and  place  it 
under  change  control. 

At  the  Specification  Review,  the  CM  will  release  the  Software  Specifications  Document  and  place  it 
under  change  control. 

At  the  Preliminary  Design  Review,  the  CM  will  review  the  Preliminary  Design  Document  to  assign 
configuration  items  according  to  the  defined  software  components,  and  update  the  Configuration  Item 
Index.  The  CM  will  also  release  the  Preliminary  Design  Document,  the  Software  Test  Plan,  and  the 
User  Document,  and  place  them  under  change  control. 

At  the  Critical  Design  Review,  the  CM  will  review  the  Software  Design  Document  to  assign 
configuration  items  according  to  the  defined  routines,  and  update  the  Configuration  Item  Index.  The 
CM  will  also  release  the  Software  Design  Document  and  place  it  under  change  control. 

The  CM  will  review  the  software  to  ensure  that  all  routines  are  fully  updated  and  have  been  tested  and 
released  to  the  Test  and  Evaluation  group. 

The  CM  will  ensure  that  all  software  components  are  fully  updated  and  have  passed  the  appropriate 
acceptance  tests. 
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4.  Records  collection  and  retention 

All  records  as  defined  in  Section  3.3  will  be  available  for  inspection  on  request.  Written  logs,  change  requests,  and 
discrepancy  reports  will  be  maintained  in  a  binder  by  the  Configuration  Manager.  RCS  logs  and  Pascal  revision  logs  will 
be  available  as  part  of  the  source  code. 

All  written  memoranda  to  and  from  the  Configuration  Manager  will  be  maintained  in  the  same  binder.  Electronic  mail 
will  be  retained  in  a  log  file. 


Software  Configuration  Management 


Support  Materials 


Typical  Revision  Control  System  Session 


James  E.  Tomayko 
The  Wichita  State  University 


The  following  annotated  typescript  is  a  typical  session  with  the  Revision  Control  System  (RCS)  tool  that  runs  on 
Unix.  It  demonstrates  the  tasks  needed  for  checking  in  and  out  controlled  modules,  shows  how  the  simultaneous 
update  problem  may  be  prevented,  and  shows  how  version  trees  may  be  created. 


Script  started  on  Thu  Aug  7  10:20:46  1986 

1  /usrO/ jet/adaprograms]  emacs  synch. a 

The  editor  is  commanded  to  open  an  Ada  source  file  synch .  a,  which  is  about  to  be  placed  under  configura¬ 
tion  control.  The  configuration  manager  enters  the  following  at  the  top  of  the  file: 

— $Header$ 

— $Log$ 

This  action  marks  for  RCS  the  location  in  the  file  to  place  the  initial  header  and  later  version  logs. 


/usrO/ jet/adaprograms]  cl  synch.; 


This  command  tells  RCS  to  check  in  the  module.  RCS  prompts  for  a  description  of  the  configuration  item  as 
follows: 

synch. a, v  < —  synch. a 
Initial  revision:  1.1 

enter  description,  terminated  with  AD  or  ' . ' : 

NOTE:  This  is  NOT  the  log  message! 

»  This  is  a  task  which  synchronizes  two  simultaneously  executing  tasks. 

»  Programmer:  James  E.  Tomayko 

»  . 

sh:  /bin/snoop:  not  found 
done 


3  /usrO/ jet/adaprograms]  Is 

ada.lib  adaone.a.BAK  calculator. a  synch. a, v 

adaone.a  adaone.a.CKP  realtime 


synch . lib 


Note  in  this  display  of  the  file  names  that  the  module  synch .  a  is  gone,  replaced  by  synch .  a,  v,  which  is 
where  the  original  file  and  the  deltas  of  the  revised  versions  of  the  file  will  be  kept. 


4  /usrO/ jet/adaprograms]  co  -1  synch. a 
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This  command  checks  out  synch .  a  for  revision.  The  -1  option  locks  the  file  and  prevents  any  other  program¬ 
mer  from  checking  out  the  same  module.  RCS  replies  as  follows: 

synch . a, v  — >  synch . a 
revision  1 . 1  (locked) 
sh:  /bin/snoop:  not  found 
done 


Note  in  this  listing  of  the  files  that  now  there  is  a  synch .  a  checked  out  of  synch .  a ,  v: 


5  /usrO/ jet/adaprograms]  Is 

ada.lib  adaone.a.CKP  synch. a  synch. lib 

adaone.a  calculator. a  synch. a, v  typescript 

adaone.a.BAK  realtime 

When  the  file  is  opened  for  editing,  the  Header  and  Log  comments  are  found  to  have  been  modified: 

6  /usrO/ jet/adaprograms]  exnacs  synch. a 

— $Header:  synch. a, v  1.1  86/08/07  10:21:40  jet  Exp  $ 

— $Log:  synch. a, v  $ 

Revision  1.1  86/08/07  10:21:40  jet 

Initial  revision 

After  the  changes  have  been  mads  to  the  file,  it  is  checked  in,  at  which  time  RCS  prompts  for  a  description  of 
the  changes: 

7  /usrO/ jet/adaprograms]  ci  synch. a 

synch. a, v  < —  synch. a 

new  revision:  1.2;  previous  revision:  1.1 
enter  log  message: 

(terminate  with  *D  or  single  ' . ' ) 

»  Added  to  comments  to  incomplete  exception  handling  statements. 

»  . 

sh:  /usr/local/lib/rdiff :  not  found 

sh:  /bin/snoop:  not  found 

done 

The  next  time  the  module  is  checked  out,  the  change  comments  appear  in  the  Log: 

8  /usrO/ jet/adaprograms]  co  -1  synch. a 

synch. a, v  — >  synch. a 
revision  1.2  (locked) 
sh:  /bin/snoop:  not  found 
done 

9  /usrO/ jet/adaprograms]  emacs  synch. a 
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— $Header:  synch. a,v  1.2  86/08/07  10:24:37  jet  Exp  $ 
$Log:  synch. a, v  $ 


Revision  1.2  86/08/07  10:24:37  jet 

Added  to  comments  tv  inconplete  exception  handling  statements. 


Revision  1.1  86/08/07  10:21:40  jet 

Initial  revision 


The  changes  made  to  the  module  during  this  check  out  actually  created  a  new  line  of  development,  so  instead  of 
checking  the  module  in  as  Version  1.3,  RCS  is  directed  to  check  it  in  as  Version  2.0: 

10  /usrO/ jet/adaprograms]  ci  -r2 . 0  synch. a 

synch. a, v  < —  synch. a 

new  revision:  2.0;  previous  revision:  1.2 
enter  log  message: 

(terminate  with  AD  or  single  '  ) 

»  Created  a  divergent  form  of  synch. a  by  adding  a  third  process  to  be 
»  synchronized. 

»  . 

sh:  /usr/local/lib/rdiff :  not  found 

sh:  /bin/ snoop:  not  found 

s|one 

Future  modifications  to  Version  1.2  can  be  made,  thus  keeping  alive  its  branch  of  the  version  tree,  by  specifying 
it  in  the  co  command  using  the  -r  option.  Actually,  any  version  of  the  module  can  be  recovered. 

More  information  about  RCS  can  be  found  in  [Tichy82]. 
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Presentation  Support  Viewgraphs 


James  E.  Tomayko 
The  Wichita  State  University 


The  following  viewgraphs  have  been  used  by  the  author  to  support  teaching  software  configuration  management 
in  an  industrial  short  course  setting.  They  appear  in  the  order  of  use. 


1.  The  Role  of  Configuration  Management 

2.  Functions  of  Configuration  Management 

3.  Commitment  to  Configuration  Management 

4.  Typical  Configuration  Items 

5.  Configuration  Management  Library  Functions 

6.  Types  of  Change  I 

7.  Types  of  Change  II 

8.  Fundamental  Principles  to  Guide  Configuration  Control  Boards 

9.  Factors  Determining  Configuration  Control  Board  Characteristics 

10.  Hierarchies  of  Configuration  Control  Boards 

1 1.  Key  Factors  in  Evaluating  Change  t 

12.  Key  Factors  in  Evaluating  Change  2 

13.  Key  Factors  in  Evaluating  Change  3 

14.  Discrepancy  Report  Evaluation  Process  Flowchart 

15.  Change  Request  Evaluation  Process  Flowchart 

16.  Simultaneous  Update  Problem 

17.  Version  Tree 

18.  Trend  Analysis 

19.  Standards  For  Configuration  Management  Plans 
Pages  34  through  52  are  unnumbered. 
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The  Role  of  Configuration  Management 
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Adapted  from  Bersoff,  Henderson  and  Siegel,  Software  Confi 
Management. 


Functions  of  Configuration 
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Configuration  Management  Library 
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Types  of  Change  l: 
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Key  Factors  in  Evaluating  Change-f 

Size  •  CPU  and  Memory 
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Key  Factors  in  Evaluating  Change2 

Criticality  of  the  Area  •  Resources  (Skills, 
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Factors  Determining  Configuration 
Control  Board  Characteristics 
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Hierarchies  of  Configuration 
Control  Boards 
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Is  There  An  Alternative? 


Discrepancy  Report  Evaluation 
Process  Flowchart 


Change  Request  Evaluation 
Process  Flowchart 
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Simultaneous  Update  Problem 
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Sample  Examinations 


James  E.  Tomayko 
The  Wichita  State  University 


The  following  exams  have  been  developed  to  test 
achievement  of  the  behavioral  objectives  in-  the 
Software  Configuration  Management  curriculum 
module  SEI-CM-4-1.0  (Preliminary). 


Exam  1 


1.  List  two  ways  that  software  changes 
throughout  the  life  cycle: 

2.  What  is  a  configuration  item? 

3.  How  does  configuration  control  maintain  the 
integrity  of  configuration  items? 

4.  Identify  the  configuration  items  of  a  typical 
product. 

5.  Define  the  term  ’baseline.’ 

6.  Give  an  example  of  a  non-ambiguous 
software  part  numbering/naming  scheme. 

7.  What  is  the  difference  between  discrepancies 
and  requested  changes? 

8.  What  is  the  difference  between  discrepancies 
caused  by  requirements  errors  and  those 
caused  by  development  errors? 

9.  List  three  key  items  included  in  a  dis¬ 
crepancy  reporting  form. 

10.  List  three  key  items  included  in  a  change  re¬ 
quest  form, 

11.  Show  how  discrepancy  reports  and  change 
requests  are  tracked  within  a  software 
development  organization. 

12.  List  and  define  the  fundamental  principles  of 
implementing  change  control  boards. 

13.  Define  the  scope  of  change  control  boards  of 
at  least  three  levels  of  a  product  develop¬ 
ment  organization. 

14.  A  change  control  board  is  given  respon¬ 
sibility  over  the  avionics  subsystem  of  a 
digitally-controlled  aircraft.  Who  should  be 
on  the  board?  Who  should  make  the  final 
decisions? 


15.  List  five  considerations  specific  to  evaluat¬ 
ing  the  repair  of  discrepancies. 

16.  List  five  considerations  specific  to  evaluat¬ 
ing  change  requests. 

17.  List  five  considerations  specific  to  evaluat¬ 
ing  requests  for  new  derivatives  of  a  product. 

18.  Specify  how  the  implementation  of  changes 
can  be  tracked. 

19.  Define  the  simultaneous  update  problem. 

20.  Define  the  concept  of  version  trees. 

21.  Identify  at  least  three  necessary  characteris¬ 
tics  of  good  version  control  tools. 

22.  List  at  least  three  commercially  available 
version  control  tools,  their  similarities  and 
differences,  and  their  suppliers. 

23.  Identify  at  least  two  standards  for  configura¬ 
tion  management  plans. 

24.  List  three  items  in  an  effective  configuration 
management  plan. 

25.  List  at  least  three  personal  characteristics 
needed  by  effective  configuration  manage¬ 
ment  personnel. 


Exam  2 


1.  Responding  to  approved  change  requests  and 

_  are  two  ways  that  software 

changes  throughout  the  life  cycle. 

2.  Documents  and  code  placed  under  con¬ 
figuration  control  are  referred  to  as 


3.  List  three  items  under  configuration  control 

in  the  course  of  a  typical  software 
development: _ . 

4.  When  an  item  is  placed  under  configuration 

control  is  often  referred  to  as  a _ . 

5.  Discrepancies  are: _ . 

6.  Requested  Changes  are: _ . 
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7.  Discrepancy  reporting  forms  should  have 

line  items  such  as: _ . 

8.  Change  requests  and  discrepancy  reports  are 

tracked  within  an  organization  by: _ . 

9.  What  should  be  considered  when  evaluating 
the  repair  of  discrepancies? 

10.  List  three  considerations  in  evaluating 
change  requests  that  differ  in  importance 
from  the  list  in  #9. 

1 1.  Define  the  simultaneous  update  problem. 

12.  Why  are  different  versions  of  a  product  often 
needed? 

13.  What  characteristics  should  a  good  version 
control  tool  have? 

14.  Where  can  guides  to  developing  configura¬ 
tion  management  plans  be  located? 

15.  List  three  items  in  an  effective  configuration 
management  plan. 

16.  What  are  System  Description  Languages? 
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Introduction 

The  following  is  a  summary  of  the  discussion  during 
the  Software  Configuration  Management  meeting 
held  at  the  Software  Engineering  Institute  in  Pitts¬ 
burgh  on  July  16,  1986.  In  this  document  I  have 
tried  to  determine  the  major  concerns  brought  up  and 
the  conclusions  reached  during  the  day  long  discus¬ 
sion.  The  discussion  ran  in  many  directions,  often 
changing  topics  quickly  and  not  returning  to  the 
original  subject  for  quite  some  time.  Therefore,  I 
did  not  try  to  summarize  the  discussion  chronologi¬ 
cally,  since  I  felt  that  would  be  more  confusing  than 
informative.  I  have,  instead,  tried  to  sort  the  various 
concerns  and  conclusions  into  specific  areas  and 
summarized  the  discussion  of  each  major  point 
brought  up  in  those  areas. 


Overview 


Definitions  of  Software  Configuration 
Management.  The  basic  definitions  of  Configura¬ 
tion  Management  that  the  workshop  participants 
more  or  less  agreed  upon  seems  the  best  place  to 
start;  since  the  definition  is  fundamental  to  the  dis¬ 
cussion  of  Software  Configuration  Management 
(SCM).  Jim  Tomayko,  the  host  of  the  workshop,  put 


as  his  capsule  description  of  Configuration  Manage¬ 
ment;  "the  disciplines  and  techniques  of  initiating, 
evaluating,  and  controlling  change  of  software 
products  during  and  after  the  development  process." 
This  definition  met  with  general  approval,  although 
the  discussion  as  a  whole  brought  out  a  much  more 
complex  and  discerning  description.  The  most  ap¬ 
parent  concept  missing  from  the  original  definition 
was  that  SCM  is  a  fundamental  and  essential 
management  tool  for  software  development  projects. 
It  is  more  a  management  concept  than  a  concrete 
structure  and  is  invaluable  to  the  organized  and  rapid 
output  of  a  software  product. 

Although  the  concept  of  SCM  was  felt  to  be  fun¬ 
damental  to  the  maintenance  of  software  products, 
the  workshop  members  felt  that  associating  SCM 
with  maintenance  is  misleading.  Configuration 
management  should  not  start  simply  when  a 
software  product  reaches  the  maintenance  phase;  the 
whole  development  process  must  be  managed  in 
such  a  way  that  SCM  can  work  properly.  For  in¬ 
stance,  if  the  original  designer  does  not  document 
his  work  properly,  then  the  configuration  manage¬ 
ment  process  breaks  down;  because  later  changes 
create  problems  not  immediately  apparent  based  on 
the  existing  documentation.  SCM  therefore  is  an  in¬ 
tegral  part  of  the  entire  software  design  and  develop¬ 
ment  process  and  a  vital  part  of  all  software  en¬ 
gineering. 

The  state  of  Software  Configuration  Management 
today.  One  of  the  major  points  of  discussion  was 
how  Software  Configuration  Management  was  being 
utilized  by  the  software  engineering  community 
today.  No  one  at  the  meeting  felt  that  SCM  was 
being  effectively  utilized  as  a  management  tool;  in 
fact,  just  the  opposite.  Although  there  have  been 
many  corporations  with  solid  SCM  programs,  there 
are  a  vast  number  of  companies  producing  software 
today  with  either  np  program  whatsoever  or  a 
programs  that  hinder  rather  than  help.  What  is 
wrong  with  the  SCM  programs  today? 

A  major  problem  is  the  lack  of  a  widespread  under- 

55 


SEI-SM-4-1.0 


Software  Configuration  Management 


Support  Materials 


standing  of  the  usefullness  of  a  solid  SCM  program. 
Although  mar;,  large  companies  do  have  configura¬ 
tion  management  systems,  often  when  they  turn  a 
project  over  to  a  smaller  contractor,  the  Software 
Configuration  Management  is  left  up  to  that  contrac¬ 
tor,  who  often  chooses  to  do  nothing.  If  the  con¬ 
figuration  management  is  bad,  one  can  almost 
guarantee  that  the  documentation  will  be  bad.  Then, 
when  the  development  process  for  a  software 
product  is  over  and  it  goes  into  maintenance  mode, 
the  contractor  turns  over  a  software  project  with  in¬ 
complete  documentation.  So  the  company  left  with 
the  project  is  lost,  they  start  playing  around  with  it, 
and  they  are  left  with  "spaghetti"  software.  Accord¬ 
ing  to  the  members  of  the  workshop,  this  kind  of 
thing  happens  all  the  time;  even  though  many  of 
these  projects  are  expected  to  interact  with  others. 

One  key  factor  in  an  effective  configuration  manage¬ 
ment  system  is  a  solid  Configuration  Control  Board 
structure.  However,  in  most  companies  today  the 
importance  of  the  boards  and  their  members  is  over¬ 
looked.  Often  the  people  put  into  these  boards  do 
not  have  the  training  or  experience  to  make  deci¬ 
sions  about  changes  or  problems  in  software 
products.  One  example  brought  up,  was  an  entire 
Software  Configuration  Management  division  that 
exists  but  is  virtually  a  hindrance  to  the  organization. 
In  this  organization  when  a  change  request  is  writ¬ 
ten,  often  only  a  paragraph  or  less  of  information, 
and  sent  into  headquarters,  it  goes  to  the  Configura¬ 
tion  Control  Division.  However,  this  division’s  job 
is  simply  to  put  a  number  on  the  CR  and  send  it  out; 
without  any  kind  of  board  meeting  or  discussion 
whatsoever.  This  CR  is  then  sent  out  to  people  who 
can’t  possibly  tell  from  a  couple  of  sentences  of  in¬ 
formation  whether  or  not  the  change  is  a  good  idea. 
Then,  after  several  weeks,  the  request  is  sent  back 
with  "nonconcur"  or  "concur"  stamped  on  it,  and  of¬ 
tentimes  it  takes  months  before  any  real  action  is 
taken  on  the  document.  If  the  change  is  approved  it 
goes  to  the  implementation  organization  that  writes 
the  functional  specification  and  the  detail  design 
with  no  review  of  either  document.  This  same  or¬ 
ganization  does  all  of  the  coding  and  testing,  without 
ever  consulting  a  review  board  or  the  originator  of 
the  request;  then  when  finally  shows  up  in  the 
field  the  originator  proba  ,  won’t  even  recognize  it. 

Many  times  the  people  at  higher  levels  of  large 
projects  don’t  understand  software  and  think  of  it  as 
simply  "another  subsystem".  It  becomes  a  difficult 
task  to  convince  these  project  managers  that  on  a 
large  complex  system,  or  any  project  that  has  as  its 
root  a  data  system,  the  software  is  an  integral  func¬ 
tion  of  the  project.  Often  in  these  projects  the  use¬ 


fulness  of  a  configuration  management  system  is 
overlooked  and  therfore  this  vital  management  tool 
is  not  used  properly.  Many  times  attempts  are  made 
to  use  other  methods,  like  the  CSSR  or  C  Spec,  sys¬ 
tem,  to  maintain  control  over  projects.  But  these 
programs  tend  to  be  cursory  measurements  of 
progress  and  costs  without  ever  getting  down  to  the 
real  work  of  change  management  It  is  in  the  con¬ 
figuration  boards  that  changes  are  discussed  and  in¬ 
formation  gets  moved  around;  where  sleeves  are 
rolled  up  and  the  nuts  and  bolts  of  the  software  are 
laid  out 

So  it  is  very  apparent  that  there  is  a  great  need  for 
improvement  in  the  area  of  Software  Configuration 
Management. .  The  problems  are  large  and 
widespread;  of  course  they  won’t  be  solved  over¬ 
night.  However,  the  workshop  participants  had  a 
great  many  ideas  about  the  components  of  an  ideal 
configuration  management  system.  These  may 
provide  the  base  for  educating  future  software  en¬ 
gineers  to  better  manage  their  projects  through 
Software  Configuration  Management. 


The  Software  Configuration 
Management  System _ 


A  general  picture.  The  workshop  more  or  less 
agreed  that  there  are  too  many  unpredictable  cir¬ 
cumstances  in  the  corporate  world  to  build  a  generic 
all  purpose  configuration  management  structure. 
However,  it  is  possible  to  sketch  in  certain  key  ele¬ 
ments  without  creating  a  definitive  structure.  Some 
of  the  elements  are  just  fundamental  characteristics 
of  a  SCM  system,  while  others  are  more  subtle 
details  that  will  create  a  more  efficient  management 
machine. 

All  large  system  projects  have  systems  of 
Change/Configuration  Control  Boards  (hereafter 
known  as  CCB’s).  The  structure  of  the  CCB’s  may 
differ  widely  according  to  the  type  of  project,  the 
company  in  charge,  and  the  size  or  cost  of  the 
program.  However,  the  CCB’s  are  a  necessary  ele¬ 
ment  to  almost  any  SCM  structure.  These  boards 
work  in  a  kind  of  waterfall  structure  with  a  great 
number  of  control  boards  at  the  lower  levels  which 
feed  up  into  the  higher  levels.  Change  usually 
bubbles  up  from  the  bottom  where  the  programming 
activity  is  boiling.  At  times  there  is  reverse  traffic 
when  change  requests  come  down  from  either  the 
customer  or  the  system  manager,  but  the  vast 
majority  comes  from  the  area  of  the  most  program¬ 
ming  activity.  Therefore  the  greatest  number  of 
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boards  is  at  this  bottom  level  of  great  activity,  and 
these  boards  should  be  the  most  active. 

Ideal  CCB  characteristics.  One  of  the  most  impor¬ 
tant  characteristics  for  any  control  board,  but  espe¬ 
cially  the  lower  level  boards,  is  that  they  should  be 
active.  Because  this  is  where  information  is  passed 
around,  where  you  begin  to  see  the  project’s  shape 
and  direction,  it  is  vital  that  the  boards  be  a  well- 
used  and  functioning  body  in  the  SCM  structure. 
The  CCB  should  be  a  place  of  discussion,  where  any 
problems  or  requests  that  come  up  in  a  project  get 
hammered  out.  On  large  projects  these  board  meet¬ 
ings  often  last  longer  than  a  full  day,  but  the  work 
being  done  in  them  is  vital. 

Because  this  work  is  so  vital  to  a  project,  "casual 
involvement"  simply  cannot  exist  in  the  CCB  sys¬ 
tem.  It  is  important  that  the  management  people  on 
each  board  look  into  eveiy  CR7DR.that  comes  before 
them.  Even  if  the  change  or  bug  is  presented  in  a 
very  casual  or  non-mission  critical  way,  it  is  the  duty 
of  the  board  members  to  look  into  it  as  if  it  were.  If 
board  members  allow  the  casual  nature  of  a  presen¬ 
tation  affect  their  decisions  and  evaluations, 
problems  may  be  overlooked  that  could  escalate 
later  into  emergency  situations. 

There  should  be  a  route  for  emergency  changes  so 
that  the  system  won’t  break  down  during  emergency 
situations.  There  should  also  be  a  CCB  appeal  route. 
This  means  that  it  would  be  possible  to  go  to  a 
higher  CCB  if  the  originator  of  the  change  request 
deemed  it  to  be  absolutely  necessary  to  reverse  the 
original  boards  decision.  This  will  help  to  keep  the 
board  meetings  from  becoming  "shouting  matches", 
and  help  people  discuss  things  rationally.  However, 
the  appeal  route  must  be  carefully  controlled, 
(perhaps  by  upper  level  boards  making  decisions  as 
to  which  appeal  request  should  be  accepted)  in  order 
to  keep  the  authority  of  the  lower  boards  intact 

It  is  important  not  to  limit  the  number  of  boards  be¬ 
cause  of  past  SCM  practices  or  "efficiency".  It  is 
actually  more  efficient  to  have  as  many  boards  as 
possible  within  cost  and  common  sense  parameters. 
Each  board  should  have  the  minimum  number  of 
people  possible  needed  to  make  decisions.  There¬ 
fore  each  CCB’s  jurisdiction  should  be  well  docu¬ 
mented,  and  only  those  people  directly  involved  in 
or  affected  by  changes  in  their  jurisdiction  need  to 
be  at  their  CCB  meetings.  This  way  only  vital 
people  are  involved  in  their  particular  CCB  deci¬ 
sions,  and  other  important  people  who  not  directly 
involved  don’t  waste  their  time. 

Ensuring  proper  documentation.  At  a  very  basic 
level  Configuration  Control  should  be  involved  with 
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all  changes  taking  place  at  the  project  level  using  a 
lot  of  discussion  and  review  for  each  change  being 
made.  In  order  for  this  to  happen,  documentation 
throughout  the  development  phase  of  a  system  must 
be  enforced.  So  in  every  SCM  structure  it  would  be 
a  good  idea  to  have  a  division  that  will  make  sure 
that  the  original  developers  are  writing  down 
everything.  Documentation  never  gets  done  by  those 
developing  the  code  without  outside  influence  and 
almost  never  gets  done  post-facto  (certainly  not 
accurately).  If  there  is  no  documentation,  there  is 
nothing  to  control.  So  the  documentation 
"enforcers"  are  a  good  idea  for  a  strong  SCM  sys¬ 
tem,  provided  their  authority  is  well  documented  and 
strictly  monitored. 

These  various  characteristics  of  a  good  SCM  struc¬ 
ture  may  vary  a  great  deal;  especially  when  the  ex¬ 
isting  authority  levels  are  very  different.  The  au¬ 
thority  hierarchy  in  a  company  or  program  has  a 
great  deal  to  do  with  the  configuration  management 
system,  and  all  the  elements  that  have  been  talked 
about  so  far  rest  upon  well-organized  authority 
levels. 


Authority  in  SCM  Systems _ 

Authority  hierarchies.  Although,  as  previously 
stated,  the  CCB’s  are  places  for  discussion  it  must 
be  stressed  at  this  point  that  the  final  decision¬ 
making  authority  should  lie  with  one  individual. 
The  control  boards  do  not  vote  on  changes;  one  per¬ 
son  makes  a  decision  under  advisement.  This  is  ex¬ 
tremely  important  when  trying  to  avoid  interproject 
politics  and  keep  a  program  oriented  toward  its 
proper  goal.  The  higher  level  boards  have  greater 
authority,  of  course,  than  the  lower  boards  and  the 
system  level  CCB  belongs  at  the  top  of  the  pyramid. 
It  is  the  head  of  the  system  level  CCB  who  has  au¬ 
thority  to  make  the  final  judgements  on  CR/DR’s 
and  any  last  minute  emergency  "patches",  although 
this  authority  is  usually  delegated  to  lower  level 
boards  who  are  more  often  confronted  with  the 
problems  as  they  come  up.  This  means  that  whoever 
is  making  those  final  decisions  had  better  be  pretty 
sharp  or  the  program  is  headed  for  trouble. 

It  is  also  healthy  to  a  project  to  have  a  slight  adver¬ 
sary  relationship  existing  between  the  software 
design  manager  and  the  head  of  the  program.  The 
design  manager  will  be  fighting  for  what  he  needs 
for  his  particular  area,  while  the  head  of  the  program 
should  be  seeing  a  more  overall  picture,  hardware 
systems  as  well  as  software.  If  both  these  people  are 
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well  trained  in  project  management,  then  the  adver¬ 
sary  relationship  will  provide  much  needed  checks 
and  balances  within  the  project  system. 

The  various  CCB’s  should  have  documentation 
readily  available  to  them  detailing  what  specific 
areas  over  which  they  have  authority.  Each  board 
needs  to  be  sure  what  decisions  they  have  authority 
over  and  how  much  authority  they  have  to  make  a 
decision.  When  CR/DR’s  come  up,  there  should 
never  be  confusion  as  to  who  is  responsible  for  look¬ 
ing  into  them.  So  it  is  very  important  that  CCB 
jurisdiction  and  authority  cover  every  area  at  some 
level,  especially  those  critical  to  the  project,  and  this 
authority  must  be  documented.  For  example,  if  the 
Testing  and  Evaluation  division  discovers  a  DR,  it 
must  be  clear  whether  they  have  the  authority  to 
make  changes  in  the  program  or  they  need  the  au¬ 
thority  of  a  higher  board  to  make  the  change;  and 
whether  this  authority  changes  in  the  event  of  a  mis¬ 
sion  critical  DR.  At  the  workshop  two  experiences 
were  given  as  examples:  in  one  situation  the 
Test/Evaluation  people  did  have  authority  to  make 
changes  even  on  non-mission  critical  DR’s,  while  in 
the  other  situation  they  simply  reported  the  DR’s  to 
higher  boards  for  action  or  the  Evaluation  people 
simply  figured  out  ways  to  work  around  non-mission 
critical  DR’s.  The  responsibility  for  these  decisions 
need  to  be  well  documented  to  avoid  confusion. 

Key  authority  concepts.  It  is  very  important  to  un¬ 
derstand  that  authority  levels  cannot  be  genetically 
structured  to  fit  any  situation.  Usually  the  structure 
of  any  given  SCM  system  depends  on  the  authority 
levels  already  in  existence  in  the  particular  company 
or  program  involved.  Any  project  manager  coming 
into  a  company  or  program  must  have  a  good  ap¬ 
preciation  for  the  existing  authority  hierarchy.  The 
Software  Configuration  Management  system  that  he 
is  going  to  instigate,  reorganize,  or  make  additions 
to,  must  be  molded  around  those  authority  levels. 

Oftentimes  the  way  people  perceive  problems  can 
create  difficulties.  While  one  person  may  see  some¬ 
thing  as  a  ’’problem",  someone  else  may  see  it  as 
simply  a  "change".  Who  has  the  authority  to  deal 
with  these  varying  perceptions?  It  may  be  that  it 
comes  under  the  authority  of  each  CCB’s  head,  or 
that  an  entirely  different  division  or  CCB  should  be 
set  up  to  deal  with  this  question.  Once  again,  this 
will  probably  depend  on  the  authority  hierarchy  al¬ 
ready  existing.  However,  it  may  also  depend  on  the 
people  in  the  program,  the  size  of  the  project,  and 
various  other  management  considerations. 

It  is  also  important  for  each  company  that  goes  un¬ 
der  contract  with  another  to  have  appreciation  for  the 


existing  authority  hierarchy  in  the  other  company  or 
organization.  When  everyone  involved  in  a  project 
understands  the  authority  structure  and  the  way  they 
are  expected  to  work  within  it,  a  smoother  operation 
and  a  more  productive  work  atmosphere  sill  result. 


Tools  for  Software  Configuration 
Management _ 

Tools  of  the  trade.  Quite  a  few  methods  for  main¬ 
taining  control  over  change  were  discussed.  Many 
were  technical  devices  that  are  well  documented  and 
available,  so  the  group  spent  very  little  time  on 
these.  Others  were  not  discussed  necessarly  as 
"tools",  but  I  felt  that  they  could  be  labeled  as  a 
specific  tool  for  software  configuration  management 
and  that  this  would  be  a  good  place  to  summarize 
them.  First,  let’s  look  at  the  naming  and/or  number¬ 
ing  of  products. 

It  was  felt  that  one  of  the  most  important  aspects  of 
any  system  for  naming  software  products  was  that  it 
be  specific  as  well  as  not  ambivilent.  A  specific  ex¬ 
ample  was  brought  up  regarding  NASA  back  when 
the  name  of  a  software  system  matched  the  mission 
for  which  they  were  being  built.  This,  however, 
soon  became  a  problem.  In  these  projects  there  is 
usually  a  very  long  time  between  when  one  starts 
building  a  software  system  and  the  time  the  mission 
it  is  intended  for  finally  flies.  Often  halfway  through 
the  maintenance  life-cycle  of  this  software,  major 
changes  are  made  in  the  project;  payloads  may  be 
swapped  or  scrapped,  as  may  the  mission  vehicles, 
and  so  on.  When  these  changes  are  made,  the  name 
of  the  mission  is  often  changed.  Then,  one  is  left 
with  a  software  system  named  for  a  mission  that 
may  not  fly  for  years  if  it  ever  goes  up  at  all.  It  is 
easy  to  see  how  this  could  become  confusing. 
Therefore,  the  software  is  now  named  and  numbered 
in  a  completely  separate  way  so  that  there  can  be  no 
relevance  to  the  mission  for  which  its  being 
developed.  What  is  important  to  see  in  this  example 
is  that  the  naming  system  had  to  be  adjusted  to  be¬ 
come  more  specific  to  the  product  as  well  as  less 
ambivilent. 

Because  various  divisions  may  have  different  names 
for  a  single  system,  and  because  communication 
must  eventually  extend  beyond  the  purely  technical 
community,  it  is  important  to  be  able  to  see  how  the 
nomenclature  evolved  and  how  the  various 
nomenclature  relate  to  one  another.  IBM  uses  a 
waterfall  diagram  to  show  the  path  of  each  particular 
system  and  its  various  names  along  the  way.  But 
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perhaps  more  importantly,  IBM  puts  on  the  same 
page  a  cross  reference  list.  Since  each  nomenclature 
may  for  a  particular  software  build  have  three  dif¬ 
ferent  names  with  each  of  these  names  understood 
by  different  divisions,  the  cross  reference  list  is  im¬ 
portant  for  clear  understanding  and  communication. 
Using  diagrams  is  also  a  useful  tool  for  communicat¬ 
ing  with  those  outside  the  technical  community. 

A  management  tool  that  might  not  be  distinctly 
thought  of  as  a  SCM  "tool",  is  that  of  using  "freeze 
dates"  when  putting  out  incremental  releases  of  a 
software  system.  The  example  at  the  meeting  went 
something  like  this:  Usually,  the  top  management 
people  on  a  project  are  very  anxious  to  see  some  sort 
of  working  software  even  though  the  software  desig¬ 
ners  are  still  working  out  the  bugs  in  a  code  and  may 
be  very  reluctant  to  release  it.  In  a  case  like  this, 
having  freeze  dates  for  the  software  to  be  turned  in 
will  force  the  developers  to  release  what  they  have 
even  if  they  feel  it  is  incomplete.  Usually  the  first 
release  will  be  chaotic  but  this  will  give  a  good  idea 
about  where  to  go  and  what  needs  to  be  fixed,  and 
the  consumer  has  a  working  product.  Even  if  it  has  a 
lot  of  DR’s,  having  a  completed  product  is  a  positive 
incentive  and  will  improve  the  working  atmosphere. 
The  freeze  dates  must  be  rigid;  if  the  developers 
don’t  get  their  projects  in  on  time,  they  won’t  be  in¬ 
cluded  in  the  release.  If  it  isn’t  enforced  the  com¬ 
puter  people  will  keep  fiddling  around  and  changing 
things,  and  the  entire  program  will  fall  behind 
schedule.  Once  again  it  is  important  to  remember 
that  implementing  a  tool  like  this  will  depend  a  great 
deal  on  the  existing  situation. 


Documentation  and  Credibility 

Documentation.  At  one  point  in  the  day’s  con¬ 
ference  Jim  Tomayko  asked  the  group  if  they  knew 
whether  anyone  paid  attention  to  the  standards  for 
software  configuration  management  put  out  by 
IEEE.  No  one  at  the  meeting  had  even  heard  of 
them.  They  were  aware  of  the  Department  of 
Defense  Standard  2167,  but  it  was  generally  ack¬ 
nowledged  that  this  was  overlooked  by  most 
program  managers.  The  standards  get  overlooked 
because  the  rigorous  documentation  requirements 
that  they  establish  are  seen  as  cumbersome  and  so 
documentation  does  not  get  enforced.  At  first,  this 
seems  easier  for  both  the  managers  and  developers. 
It  isn’t  until  they  are  waste  deep  in  the  mire  of  unmet 
schedules,  undocumented  software  with  hundreds  of 
unseen  DR’s,  rising  costs,  and  consumers  anxious  to 


see  this  project  that  is  now  out  of  control,  that  the 
importance  of  enforced  documentation  standards  is 
apparent  How  do  you  motivate  people  to  use  cum¬ 
bersome  standards  when  they  haven’t  been  "burned" 
by  past  experience?  Obviously,  standards  for 
software  configuration  management  are  a  useful 
tool,  but  getting  people  to  use  them  is  another  mat¬ 
ter. 

It  cannot  be  said  enough  that  without  documentation 
there  is  nothing  to  put  under  configuration  control. 
There  must  be  a  valid  functional  specification  docu¬ 
ment  in  order  to  get  past  the  Preliminary  Design 
Review  or  there  is  nothing  to  put  under  the  manage¬ 
ment  system  and  you’re  already  off  schedule.  A 
brief  list  of  documentation  includes: 

•  requirement  specification  documents, 

•  functional  specification  documents, 

•  detail  design  documents, 

•  user  manuals, 

•  maintenance  manuals, 

•  interface  control  documents, 

•  memory  layouts, 

•  test  plans, 

•  and  the  code  itself,  of  course. 

All  of  this,  plus  more  not  mentioned  here,  comes  un¬ 
der  maintenance  control,  unless  it  is  subject  to  a 
project  specific  waiver.  Because  many  of  these 
documents  are  scrapped  when  a  product  reaches 
maintenance  phase,  it  would  be  useful  perhaps  to 
maintain  a  configuration  index  for  each  product  so 
that  enough  documentation  is  maintained  for  con¬ 
figuration  control  during  the  maintenance  phase. 

Even  in  the  essential  area  of  documentation  there 
must  be  consideration  for  the  project  involved.  If 
the  project  is  large  the  managers  are  usually  more 
careful  about  enforcing  documentation  because  the 
project  as  a  whole  is  probably  being  approached  in  a 
veiy  careful  and  cautious  way.  However,  in  a 
smaller  project  SCM  tends  to  take  a  back  seat  and 
the  documentation,  therefore  ,  doesn’t  seem  impor¬ 
tant  or  economical.  Sometimes  full  rigor  on  the 
SCM  and  documentation  can  be  relaxed  slightly  on  a 
smaller  project,  but  then  you  need  someone  in  com¬ 
mand  who  knows  when  full  rigor  can  be  relaxed  and 
when  it  should  be  enforced.  However,  good 
documentation  will  always  help  configuration 
management  people  to  make  sounder  judgements 
and  more  credible  evaluations. 

Credibility..  Good  basic  documentation  is  the  basis 
for  Configuration  Control  Board  evaluations  on  the 
issues  before  them.  In  order  for  CCB’s  to  make  in- 
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telligent,  rational,  and  credible  decisions  on 
CR/DR’s  there  is  certain  data  that  is  necessary.  This 
data  should  be  well  documented  so  that  the  CCB 
evaluation  of  the  data  will  carry  weight.  This  list  of 
necessary  data  was  developed  at  the  workshop: 

•  The  size  of  the  change. 

•  Are  there  alternatives?  Would  it  be  rela¬ 
tively  simple  to  work  around  whatever  is  be¬ 
ing  changed? 

•  The  complexity  of  the  change.  Does  it  refer¬ 
ence  other  systems?  Does  this  system  sup¬ 
port  other  software  or  rely  on  other  support 
software  that  would  need  to  be  changed  ac¬ 
cordingly? 

•  The  need  date.  Basically,  the  board  needs  to 
know  how  much  time  they  would  have  to 
make  the  change  and  test  it,  before  the  con¬ 
sumer  needs  a  working  project. 

•  Impact.  This  is  related  to  its  complexity. 
What  kind  of  effect  will  this  change  have  on 
subsequent  work.  The  board  needs  to  look 
down  the  road  a  bit  and  see  where  the  project 
is  going. 

•  Cost.  How  much  will  the  change  cost? 
Also,  will  this  change  save  money  in  the 
overall  project? 

•  The  criticality  of  the  area.  NO  CR/DR’s  can 
be  overlooked  if  the  problem  will  prove  to 
be  mission  critical.  All  other  areas  of  evalua¬ 
tion  should  be  rethought  if  the  bug  might 
possibly  create  critical  problems. 

•  Other  CR’s  under  current  evaluation.  Will 
another  change  solve  this  problem  or  do 
other  more  critical  changes  rely  on  this 
software  remaining  the  same. 

•  Test  requirements.  This  area  takes  in  how 
much  testing  will  be  needed  which  will  af¬ 
fect  the  costs  and  time  needed  for  the 
change. 

•  Resources.  Do  you  have  the  people  avail¬ 
able  to  work  on  this  program?  Do  you  have 
the  hardware  equipment  available  to  use  for 
this  change? 

•  CPU  and  memory  impact. 

•  Benefit  How  much  of  an  advantage  will  it 
be  to  change  the  software? 

•  Politics.  In  the  corporate  and  commercial 
world,  it  would  be  good  idea  to  evaluate  who 
is  asking  for  the  change  and  whether  or  not 
the  board’s  decision  might  be  used  as  a  bar¬ 
gaining  point  in  the  future. 


•  Maturity  of  the  change.  How  long  has  the 
change  been  before  the  board?  If  it  is  still 
considered  to  be  worthwhile  to  change 
something  after  a  long  time  has  passed,  then 
the  board  should  consider  it  more  carefully. 

By  using  this  data,  you  can  often  minimize  the  num¬ 
ber  of  "side  effects"  that  the  changes  you  are  making 
will  have.  Even  if  the  side  effects  are  unavoidable, 
the  use  of  this  carefully  documented  evaluation 
process  may  help  to  identify  where  those  effects  are 
going  to  be.  Of  course,  at  this  time  it  is  impossible 
to  be  absolutely  sure  that  all  the  side  effects  have 
been  discovered.  For  example,  suppose  there  are 
two  changes  that  are  being  made  at  the  last  minute  in 
an  emergency  situation  and  they  are  each  tested  and 
evaluated.  It  is  possible  that  although  they  may  have 
no  real  side  effects  on  the  system  separately,  when 
they  are  "patched"  in  at  the  last  minute  they  may 
have  serious  side  effects  together.  This  is  the 
greatest  fear  when  dealing  with  late  patches,  but 
careful  documentation  and  evaluation  of  the  data  in¬ 
volved  in  each  change  may  help  to  alleviate  some  of 
the  guesswork. 

In  the  purely  commercial  arena,  credibility  is  the  key 
in  dealing  with  the  marketing  division  or  the  cus¬ 
tomer.  If  they  have  a  change  request  that  is  going  to 
create  more  difficulty  than  it  is  worth,  the  configura¬ 
tion  management  people  should  be  able  to  show 
documented  data  that  will  make  the  control  board’s 
evaluation  credible.  When  a  customer  can  see  the 
kind  of  impact  a  change  is  going  to  have  on  the  time, 
size,  or  cost  involved  in  a  project,  they  will  better 
understand  and  more  readily  accept  the 
management’s  decisions  regarding  the  project.  The 
key  is  a  thorough  and  well  documented  evaluation 
based  on  the  previous  listed  data.  The  list  can  be 
changed  or  expanded  on,  according  to  the  needs  of 
the  project,  but  as  it  stands,  it  gives  a  fairly  accurate 
picture  of  the  kind  of  information  that  is  going  to  be 
needed  for  credible  evaluation. 


SCM  and  the  Real  World 


Going  from  the  classroom  to  the  corporation. 
Two  points  came  up  early  in  the  meeting  that  helped 
to  categorize  many  of  the  problems  discussed  later  in 
the  day. 

1.  We  live  in  an  irrational  world,  but  computer 
science  and  software  engineering  is  based  on 
concrete  and  rational  logic.  How  does  one 
make  this  rational  knowledge  fit  into  an  ir- 
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rational  world?  Software  Engineering  and 
Design  is  not  just  like  it  is  in  the  textbooks. 

2.  Very  often  the  existing  system  dictates  what 
kind  of  changes  take  place  and  what  kind  of 
configuration  management  is  used,  rather 
than  the  ideal  or  proper  software  design 
practices. 

Both  of  these  concepts  are  difficult  to  teach  to 
young,  inexperienced  software  engineers  who  are 
coming  directly  from  the  classroom.  They  are  con¬ 
cepts  that  are  usually  learned  through  experience.  A 
software  engineering  graduate  expects  to  put  the 
principles  of  Software  Configuration  Management 
directly  into  effect.  Suddenly  they  are  confronted 
with  an  irrational  world  that  does  not  easily  follow 
the  logical  course  of  configuration  management.  It 
isn’t  the  mainline  textbook  problems  that  are  going 
to  throw  an  educated  software  engineer;  instead,  it’s 
the  small  peripheral  problems  that  build  up  and  take 
control  of  a  project.  These  little  things,  the  result  of 
this  irrational  world,  include  corporate  politics,  un¬ 
foreseeable  accidents,  human  personalities,  and  day 
to  day  unexpected  emergencies.  Also,  a  new 
program  manager  may  have  to  deal  with  a  system 
that  does  not  follow  regulation  SCM  practices  and 
does  not  want  to  change.  Often  corporations  have 
become  comfortable  with  a  particular  structure  that 
does  not  have  room  for  SCM,  and  it  can  be  quite 
frustrating  to  a  young  manager  to  be  asked  to  com¬ 
ply  with  "company  policy"  rather  than  smart 
software  configuration  management. 

There  are  some  attributes  of  the  irrational  world  and 
some  system  protocol  specifications  that  will  never 
be  able  to  be  changed,  regardless  of  a  software 
engineer’s  chagrin  when  dealing  with  them.  Learn¬ 
ing  to  deal  with  these  inexplicable  and  usually 
frustrating  areas  of  SCM  requires  experience  in  the 
world  where  they  exist  A  textbook  will  never  be 
able  to  adequately  transfer  the  kind  of  knowledge 
needed  to  deal  with  the  irrational  world,  There  will 
always  be  people  who  will  be  able  to  manage  cor¬ 
porate  software  configuration  better  than  others, 
regardless  of  classroom  performance— another  result 
of  that  irrational  world. 

A  few  well  educated  configuration  management  per¬ 
sonnel  are  not  going  to  make  much  of  an  impact  on 
Software  Configuration  Management  today.  There 
must  be  a  way  to  communicate  the  concepts  of  SCM 
to  a  great  number  of  people  involved  in  the  develop¬ 
ment  of  software  products,  even  the  people  who  are 
not  directly  responsible  for  the  configuration 
management  of  a  particular  system  (this  would  in¬ 
clude  everyone  from  the  computer  scientist  writing 


the  actual  code  to  the  final  consumer  of  the  product). 
If  a  few  concepts  of  SCM  are  known  by  a  majority 
of  people  dealing  with  the  development  of  a 
software  product,  then  people  will  be  able  to  func¬ 
tion  more  smoothly  within  the  system  and  the  whole 
process  will  be  tighter.  This  is  also  important  when 
you  remember  the  large  number  of  companies  that 
are  using  contracts  and  subcontracts  with  other  com¬ 
panies.  Unless  the  concepts  of  SCM  are  widespread 
among  many  companies,  Software  Configuration 
Management  will  be  dependent  upon  whether  a  sub¬ 
contractor  chooses  to  use  SCM  or  not. 

Two  Perspectives.  One  last  point  that  seemed  to  be 
emphasized  at  the  meeting  was  that  of  two  perspec¬ 
tives  emerging.  It  has  been  previously  stated  that 
when  a  company  goes  under  contract  with  another  to 
develop  a  software  system,  the  management  people 
should  have  respect  for  the  existing  SCM  structure 
in  the  contracting  company.  The  two  perspectives 
are  (1)  that  of  the  originator  of  the  project  and  (2) 
that  of  the  contractor  that  goes  into  this  program. 
NASA  is  a  good  example.  They  will  often  put 
several  companies  under  contract  for  a  single  mis¬ 
sion  and  these  companies  often  turn  around  and  sub¬ 
contract  another  company  to  work  on  various  parts 
of  the  system.  NASA  has  a  very  structured  system 
for  configuration  management,  and  the  companies 
under  contract  often  have  SCM  systems  of  their 
own.  It  is  very  clear  to  see  that  being  able  to  see  the 
"give  and  take"  needed  in  a  situation  like  this.  Each 
company  needs  to  try  and  comply  with  the  SCM 
demands  of  the  contract  originator.  When  a 
software  engineer  is  trying  to  take  the  concepts  of 
SCM  into  the  real  world,  he  should  be  prepared  to 
deal  with  these  perspectives. 


Conclusions 


It  is  apparent  to  me  that  Software  Configuration 
Management  courses  are  essential  to  progress  within 
Software  Engineering  today.  SCM  is  tied  to  every 
stage  of  software  product  development.  A  good 
configuration  management  team  could  make  the  dif¬ 
ference  between  products  coming  in  on  time,  within 
cost  and  coming  in  late,  full  of  bugs,  with  greater 
costs.  Education  seems  to  be  the  place  to  start,  but 
there  seems  to  be  much  more  involved  than  class¬ 
room  development  alone.  It  seemed  that  what  the 
group  was  trying  to  do  was  begin  a  program  that 
would  teach  software  engineers  that  they  need  to 
learn  the  concepts  of  Software  Configuration 
Management  wherever  that  education  amy  be  avail- 
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able  (whether  learning  in  the  classroom  or  gaining 
experience  in  the  field).  I  would  conclude  that  what 
seems  to  be  wrong  in  Software  Configuration 
Management  today  is  that  too  many  software  en¬ 
gineers  don’t  seem  to  think  they  are  missing  much 
without  a  solid  knowledge  of  SCM.  If  they  can  be 
shown  the  importance  of  SCM,  then  perhaps  they 
will  be  more  eager  to  learn  its  concepts  and  to  use  it 
more  often  and  more  effectively  in  the  software 
development  field  today. 
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This  is  a  bibliography  of  documents  related  to  the 
problem  of  version  control  and  configuration 
management.  Specifically,  it  concentrates  on  the 
problem  of  System  Modelling,  which  is  loosely 
defined  to  be  the  task  of: 

Giving  programmers  help  in  describing  the 
structure  of  large  systems:  getting  consistent 
versions  of  files,  replacing  single  modules 
within  a  running  system,  and  recompiling  and 
rebinding  just  what  has  been  changed,  all  in 
the  right  order.  ( From  a  Xerox  internal 
glossary) 

Most  of  the  documents  do  not  attack  the  whole 
problem  just  defined,  but  together  they  represent 
work  done  on  many  aspects  of  the  problem.  Some 
are  on  various  programming  languages  that  help  the 
construction  of  large  systems.  Others  refer  to 
specific  systems  designed  to  help  programmers  in 
the  problem  of  version  control,  or  configuration 
management.  Some  even  try  to  solve  many  of  these 
problems  in  a  coherent  way.  This  problem  has 
gained  attention  recently  as  the  problems  of  larger 
projects  written  by  many  programmers  are  realized. 
Some  of  the  recent  efforts  were  reported  in  the 
proceedings  of  the  ACM  Software  Engineering 
Symposium  on  Practical  Software  Development  En¬ 
vironments  and  the  GTE  Workshop  on 
Programming-in-the-Large  that  are  listed  here. 
Some,  but  not  all  of  the  papers  from  those  proceed¬ 
ings  are  referenced  here.  This  year’s  ACM  Software 
Engineering  Symposium  should  promise  to  present 
more  recent  work.  The  list  is  by  no  means  complete. 
I  have  mainly  included  documents  that  are  publically 
(sic)  available.  I  have  also  not  included  internal 
memos  or  any  works  in  progress.  Since  I  expect 
many  new  works  this  year,  this  serves  to  capture 
some  of  the  early  work.  I  will  try  to  augment  it  as  in 
the  future.  This  bibliography  is  derived  from  a  ver¬ 


sion  I  once  distributed  on-line,  but  I  have  deleted  all 
reverences  to  various  internal  memos  and  added  new 
references. 

I  hope  this  reading  list  will  help  those  planning  to 
build  systems  to  solve  this  problem,  or  those  who 
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